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Abstract 

This technical note introdnces the Python bindings for libcloudph++. The libcloudph++ is a C++ hbrary of algorithms 
for representing atmospheric clond microphysics in numerical models. The bindings expose the complete functionality of the library 
to the Python users. The bindings are implemented using the Boost.Python C++ library and use NumPy arrays. This note 
includes listings with Python scripts exemplifying the use of selected library components. An example solution for using 
the Python bindings to access hbcloudph++ from Fortran is presented. 


1 Introduction 

This paper describes how to use the libcloudph++ from the Python^ 
programming language. The libcloudph++^ is a free and open- 
source C++ library of algorithms for representing cloud micro¬ 
physics in atmospheric numerical models. A detailed description of 
the library and its C++ interface has been described in [4]. In short, 
the library covers three numerical schemes describing processes oc¬ 
curring in warm clouds (i.e. in the absence of ice). The represented 
processes cover cloud-droplet condensational growth and formation 
of rain drops through collisions and coalescence. The first imple¬ 
mented scheme is a simplistic, so-called single-moment bulk scheme 
that allows predicting the total mass of cloud water and of rain wa¬ 
ter in a volume of air. The second scheme is a double-moment bulk 
scheme that adds prediction of the number concentration of cloud 
droplets and rain drops. The third scheme is based on the concept 
of particle tracking. The particle-based scheme implemented in 
libcloudph++ represents collisional growth of particles using a prob¬ 
abilistic Monte-Carlo type model. Furthermore, it is implemented 
for use on both multiple CPU threads as well as on a GPU. 

Access to libcloudph++ from Python is provided through so- 
called bindings. The bindings to libcloudph++ allow using the li¬ 
brary from Python, without requiring the user to interact with the 
native C++ interface. The P^hon bindings significantly facilitate 
the use of the library and add relatively little runtime overhead 
(particularly in the case of the resource-intensive particle-based 
scheme). Python has simpler syntax than C++, its philoso¬ 
phy emphasises succinct code (see [3] for a geoscience-relevant 
case study comparing Python, C++ and Fortran). Moreover, 
Python is widespread across the atmospheric science commu¬ 
nity [7]. The vast availability of software packages for interfacing 
Python codes from other languages [6] makes the Python bindings 


a good starting point for using libcloudph++ from other languages, 
for instance from Fortran. Arguably, the embraced approach 
makes the best out of salient features of two languages by using: 

C++ for implementing nmnerically-intensive concurrency-enabled 
algorithms for both CPU and GPU, and encapsulating them 
in a library; 

Python for equipping the hbrary with rapid-development fea- 
trues and for interfacing with other languages. 

This note is intended as a companion to the documentation of 
the library presented in [4] and is structured as follows. Section 2 
presents the programming interface of the Python bindings. It in¬ 
cludes examples of Python code with calls to two out of foru 
components of the library, namely the commons (section 2.1) and 
the single-moment bulk scheme (section 2.2). Section 3 exem¬ 
plifies how to use the Python bindings to call the libcloudph++ 
from Fortran. Appendix A describes how to obtain and install 
libcloudph++ and the Python bindings. 

2 Summairy of the Python interface 

All elements of the Python bindings for libcloudph++ are con¬ 
tained in the libcloudphxx Python package. Naming of the 
package components closely follows the native C++ interface. 
The PMhon package contents are summarised in Table 1 and de¬ 
scribed through examples in the following subsections. 

The current version of the package is compatible with Python 2 
only. The Python interface uses NumPip arrays. Error han¬ 
dling is carried out by translating C++ exceptions into Python 
RuntimeError exceptions. The bindings are implemented in C++ 
using the Boost.Python^ C++ library [1]. 


^http://python.org/ 

^http://libcloudphxx.igf.fuw.edu.pi/ 
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®http: //numpy. org/ 

"'http: //boost. org/libs/python/ 




Table 1: Contents of the libcloudphxx Python package. The a.<b,c,d> notation indicates that b,c,d are all attributes of a. 
The blk_2m and Igrngn modules listed at the bottom of the table are part of the bindings but are not described in this note. 


item 

type 

summary 

example 

git revision 

string 

version number 

Lst. 1 

common 

module 



common. <R_v, R_d, eps, c_pd, c_pv, g, p.lOOO, rho_w> 

floats 

physical constants 

Lst. 2 

common.th_std2dry(th, rv) 

function 

converts 9 to 9d 

Lst. 3 

common.th_dry2std(th, rv) 

function 

converts 9d to 9 

Lst. 3 

common.T(th_d, rh_d) 

function 

implements Eq. A14 in [4] 

Lst. 3 

common.p(rh., rv, T) 

function 

implements Eq. A15 in [4] 

Lst. 3 

common. p_vs (T) 

function 

implements Eq. 15 in [2] 

Lst. 4 

common.rw3_cr(rd3, kappa, T) 

function 

critical radius cubed [8] 

Lst. 6,10,11 

common.S cr(rd3, kappa, T) 

function 

critical saturation [8] 

Lst. 6,10,11 

blk_lm 

module 



blk_lm.opts_t 

class 

scheme options 

Lst. 8 

blk_lm. opts_t. <cond, cevp, revp, conv, accr, sedi> 

bools 

process togghng flags 

Lst. 8 

blk_lm. opts_t. r_c0 

float 

autoconversion threshold 

Lst. 8 

blk_lm.opts_t.r_eps 

float 

saturation adjustment tolerance 

Lst. 8 

blk_lm.adj_cellwise(opts, pd, Od, Ty, Vc, Vr, At) 

function 

condensation 

Lst. 9 

blk_lm.rhs_cellwise(opts, Tc, Tr, Vc, Vr) 

function 

coalescence 


blk lm.rhs coluinnwise(opts, pd, Vy, Az) 

function 

sedimentation 


blk_2m 

module 



Igrngn 

module 




After successful installation (see appendix A), the program 
given in Listing 1 will print the version number of the library 
expressed as a git revision id. 

I- Listing 1 - 1 

import libcloudphxx 

print libcloudphxx.git_revision 


2.1 Commons 


_ Listing 3 _ 

from libcloudphxx import common 

tht = 300 ^ K 
r_v = .01 # kg/kg 

tht_d = common.th_std2dry(tht, r_v) 
assertCtht == common.th_dry2std(tht_d, r_v)) 

rho_d =1 # kg / m3 
T = common.!(tht_d, rho_d) 
p = common.p(rho_d, r_v, T) 


The libcloudphxx. common module contains a collection of phys¬ 
ical constants and formulae. The constants exposed through the 
Python bindings can be printed with the instructions in Listing 2. 


- Listing 2 - 

from libcloudphxx import common 

print "R_d:", common.R_d # gas constant for dry air 

print "R_v:", common.R_v # gas constant for water vapour 

print "eps:", common.eps # ratio of the above 

print "c_pd:", common.c_pd # specific heat of dry air 

print "c_pv:", common.c_pv # specific heat of water vapour 

print "g:", common.g # acceleration due to gravity 

print "p_1000:", common.p_1000 # reference pressure of 1000 hPa 
print "rho_w:", common.rho_w # density of water 


As of the current release, there are seven formulae available 
in the common module of the Python bindings, see Table. 1. 
The first four functions convert the thermodynamic variables used 
in libdoudph++ (dry-air potential temperature 0^, dry-air density 
Pd, water vapour mixing ration ry) to other commonly used 
variables (for details, see appendix A in [4]). Listing 3 presents ex¬ 
ample use of two functions for converting between the 9d and the 
standard potential temperature. It also depicts how to use the 


functions for diagnosing the temperature T as a function of 9d 
and Pd, and for diagnosing the pressure p as a function of pd, ry 
and T (eqs. A14 and A15 in [4]). 

The p_vs(T) function calculates the saturated vapour pres¬ 
sure as a function of temperature using an analytic solution to the 
Clausius-Clapeyron equation used in the library. Listing 4 depicts 
example use of this function to calculate the boiling temperature 
of water for atmospheric pressure of 500 hPa. Output of the 
program is given in Listing 5. 

Note that the formulae implemented in the common module ac¬ 
cept and return only double-precision scalars, hence the need to use 
T[0] in the definition of fun(T) in Listing 4 (the SciPy'’ root 
routine uses NumPy arrays even for single-equation problems). 

The last two functions available in the common module com¬ 
pute the critical radius and the critical saturation (see chapter 5 
in [5]) using the kappa-Kohler parameterisation of hygroscopicity 
of water-solution droplets [8]. Listing 6 shows an example Python 

®http: //scipy. org/ 
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_ Listing 4 

from libcloudphxx import common 
from scipy import optimize 


. Listing 8 


from libcloudphxx import blk_lm 


opts = blk_lm.opts_t() 


print "cond 
print "cevp 
print "revp 
print "conv 
print "accr 
print "sedi 
print "r_cO 
print "r_eps 

# . . . 


opts.cond 
opts.cevp 
opts.revp 
opts.conv 
opts.accr 
opts.sedi 
opts.r_cO 
opts.r_eps 


(sedi). There r_cO controls the threshold on cloud water mixing 
ratio above which autoconversion begins. The r_eps is the ab¬ 
solute tolerance in terms of mass mixing ratio that controls the 
number of iterations within the saturation adjustment procedure. 
For further details, see description of Listing 3.1 in [4]. An instance 
of opts_t is expected as the first argument of the functions that 
constitute the interface of the single-moment scheme. 

The blk_lm. adj_cellwise() function implements the satu¬ 
ration adjustment procedure. It models the condensational growth 
of cloud droplets as well as the evaporation of water from cloud 
droplets and rain drops. An example calling sequence is presented 
in Listing 9 which is assumed to be a continuation of the code in 
Listings. The adj_cellwise() function expects: an instance 
of opts_t, five NumPy arrays of the model variables and a value 
of timestep dt. The five arrays are expected to contain values 
of the dry-air density pd, that is not altered in the call, and four 
model state variables 0d, r^, Tc, Vr- A call to adj_cellwise() 
modifies the state variables. In the presented example, the arrays 
have only one element what corresponds to a parcel-model set¬ 
up. If multi-element arrays are given, the saturation adjustment 
procedure is applied on each element. 

- Listing 9 - 


from numpy import array 

rhod = array([l. ]) 
th_d = array([305. ]) 
r_v = array([0.01 ]) 
r_c = array([0.001]) 
r_r = array([0.001]) 
dt =1 

blk_lm.adj _cellwise(opts, 

rhod, # array, read-only 

th_d, r_v, r_c, r_r, # arrays, read-write 
dt # scalar 

) 

print "r_v:", r_v, "r_c:", r_c, "r_r:", r_r 
# . . . 


p_atm = 50000 # Pa 

# p_atm = p_vs(T_boil) 
def fmi(T) : 

return p_atm - common.p_vs(T[0]) 
zero = 273.15 

res = optimize.root(fun, zero+100) # first guess: 100 C 
assert (res.success) 

print "T_boil 0 {0:g}- hPa: {l:g}- C".format( 
p_atm / 100, 
res.x[0] - zero 

) 

_ Listing 5 _ 

T.boil @ 500 hPa: 81.7841 C 


script generating a table of values of critical radius and supersat¬ 
uration for five different nucleus radii (compare Table 5.1 in [5]). 
Output of the script is given in Listing 7. 

I_ Listing 6 __ 

from libcloudphxx.common import rw3_cr, S_cr 

kappa = 1.28 # [1] 

T = 273 # [K] 

print ’{0: >10}{1: >10}{2: >10}’ .format( 

’rd [um]’,’r* [um]’,’S*-l [%] ’ 

) 

for rd in (.0223, .0479, .103, .223, .479): # urn 
rd3 = pow(rd * le-6, 3) 

print ’{0: >10g}{l: >10.2g}{2: >10.2g}’ .format( 
rd, 

(rw3_cr(rd3, kappa, T)**(l/3.))*le6, 

(S_cr(rd3, kappa, T) - 1) * 100 

) 


Listing 7 


rd [um] 

r* [um] 

S*-l [7,] 

0.0223 

0.19 

0.39 

0.0479 

0.61 

0.13 

0.103 

1.9 

0.04 

0.223 

6.1 

0.012 

0.479 

19 

0.004 


2.2 Single-moment bulk scheme 

Access to the single-moment bulk scheme implemented in lib- 
cloudph++ is provided through the libcloudphxx. blk_lm mod¬ 
ule. The single-moment scheme extends the set of model state 
variables by adding two mass mixing ratios, namely the cloud 
water mixing ratio Cc and the rain water mixing radio Vr- 

Options of the scheme that can be altered at runtime are 
grouped as attributes of the blk_lm. opts_t class. The default 
values of all options are set upon creating an instance of opts_t, 
see Listing 8. 

Among the options, there are Boolean flags for toggling conden¬ 
sation (cond), cloud-water evaporation (cevp), rain-water evap¬ 
oration (revp), autoconversion of cloud water into rain (conv), 
accretion of cloud water by rain (accr) and sedimentation of rain 


The rhs_cellwise() and rhs_columnwise() functions im¬ 
plement representation of the collision-coalescence and the rain- 
sedimentation processes, respectively. They both takes five ar¬ 
guments, and they both expect the first one to be an instance 
of opts_t. 
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Listing 11 (test.f) 


module test 
interface 

function f3cirg(al,a2,a3) bind(c) 
use iso_c_binding 
real(c_double) :: f3arg 
real(c_double) , value :: al,a2,a3 
end 

end interface 

contains 

subroutine main(rw3_cr_p, S_cr_p) bind(c) 
use iso_c_binding 

type(c_funptr), value :: rw3_cr_p, S_cr_p 

procedure(f3arg) , pointer :: rw3_cr, S_cr 
call c_f_procpointer(rw3_cr_p , rw3_cr ) 
call c_f_procpointer(S_cr_p , S_cr ) 

block 

real, dimensionCB) :: rd = (/.0223, .0479, .103, .223, .479/) 
real(c_double) :: kappa = 1.28, T = 273, rd3 
integer :: i 

print ’(3A10)’ , ’rd [um]’ , ’r* [um]’ , ’S*-l [%]’ 
do i=l, size(rd) 

rd3 = (rd(i) * le-6)**3 
print ’(3G10.2)’, & 

rd(i), & 

(rw3_cr(rd3, kappa, T)**(l/3.))*le6, & 

(S_cr(rd3, kappa, T) - 1) * 100 
enddo 
end block 
end 
end 


For rhs_cellwise(), the next two arguments are NumPy ar¬ 
rays to which the tendencies of cloud- and rain-water mixing ratio 
will be added. The last two arguments are NumPy arrays storing 
cloud- and rain-water mixing ratios; these will not be modified. 

For rhs.columnwiseO, the second argument is a NumPy ar¬ 
ray to which the tendency of rain-water mixing ratio will be added. 
The third argument is expected to be a NumPy array with values 
of dry-air density. The array can have the same shape as other 
arrays, or can be a single-column array. The fourth argument 
is expected to be a NumPy array of rain-water mixing ratios 
and will not be modified. The last argument is the vertical grid 
spacing. The second and the third dimensions axe treated as the 
vertical ones for 2-D and 3-D arrays, respectively. It is assumed 
that the indices of the array increase with height. 

3 Accessing libcloudph++ from Fortran via Python 

Python is an efficient “glue” language for coupling codes written 
in different programming languages. In this section, we present 
an example solution for accessing libdoudph++ from Fortran using 
the Python bindings. It is implemented using the CFFI® (C For¬ 
eign Function Interface) Python package and the ISO_CBINDING 
module that is part of the Fortran 2003 standard. Despite the 
fact that both CFFI and IS0_C_BINDING are intended for inter¬ 
facing code written in the C language, the presented solution 
does not require a C compiler. 


The code exemphfying the use of libcloudph++ from Fortran 
is presented in Listings 10 and 11. The code prints the same table 
of critical radii and supersaturations as the one from Listing 6 
but doing the calls to libcloudph++ from Fortran. 

The central idea is to provide a common addressing space 
for Python and Fortran, so that it is possible to refer to the 
Python code from Fortran and vice versa. To implement such 
C-F-l-/Python/Fortran coupling, the Fortran code is compiled 
as a shared hbrary to be loaded from Python. 

Example commands to compile and execute the codes from List¬ 
ings 10 and 11 are presented in Listing 12. First, the gfortran 

®http://cff1.readthedocs.org/ 


- Listing 12 - 

gfortran -ffree-form -std=f2008 -shared -fPIC test.f -o test.so 
LD_LIBRARY_PATH=. python test.py 


compiler is instructed to compile test.f into a shared hbrary 
test. so. Second, the Python script is run being instructed 
to include the current directory (“. ”) in the shared-library search 
path. Consequently, even though the goal is to call Python from 
Fortran, the control flow starts in Python. 

In the Python code in Listing 10, the test. so library is loaded 
by using the CFFI’s interface to the dlopenO system call. In or¬ 
der to enable accessing the Fortran subroutine main, the datat 5 q)es 
of the arguments of main are specified using the CFFI’s cdef 
function. The void* pointers are interpreted as function pointers 
within main. The CFFI “callback” mechanism is used to create 
callback objects for which Fortran-compatible function pointers 
can be obtained. The callback objects are defined as functions 
with the definition prepended with a Off i. callback decorator. 
The decorator includes the C signature of the function. The sig¬ 
nature specifies the datatypes of the return value and of the argu¬ 
ments. The callback objects defined in this way are then passed 
as arguments to main. 

In the Fortran code in Listing 11, the definition of sub¬ 
routine main is preceded by a definition of an interface to 
a three-argument function. Both the interface and the main 
subroutine are assigned with the bind(c) attribute which en¬ 
sures CFFI-compatible naming of functions in the shared library. 


_ Listing 10 (test.py) 

from cffi import FFI 

from libcloudphxx import common 

ffi = FFIO 

lib = ff i .dlopenC'test .so") 

ffi.cdef ("void main(void*,void*); ") 

Offi.callback ("double(double,double,double)") 
def rw3_cr(rd3, kappa, T): 

return common.rw3_cr(rd3, kappa, T) 

Offi.callback ("double(double,double,double)") 
def S_cr(rd3, kappa, T): 

return common.S_cr(rd3, kappa, T) 

lib.main(rw3_cr, S_cr) 
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_ Listing 14 _ 

git clone http://github.com/igfuw/libcloudphxx 

cd libcloudphxx 

mkdir build; cd build 

cmake .. 

make all test 

sudo make install 


The arguments to main are defined as C function pointers. 
Within main, the three-argument function interface is used to 
define two Fortran function pointers rw3_cr and S_cr. The 
Fortran function pointers are associated with the C ones by 
calling the c_f _procpointer subroutine (defined in the stan¬ 
dard ISO_C-BINDING module). Afterwards, the rw3_cr and 
S_cr can be used as any other function in Fortran. 

Output from execution of the two commands from Listing 12 
is presented in Listing 13. It matches the result obtained with 
Python code from listing 6 presented in Listing 7. 

I_ Listing 13 __ 


rd [um] 

r* [um] 

s*-i ra 

0.22E-01 

0.19 

0.39 

0.48E-01 

0.61 

0.13 

0.10 

1.9 

0.40E-01 

0.22 

6.1 

0.12E-01 

0.48 

19. 

0.40E-02 


4 Remarks 

The presented bindings to libcloudph++ provide access to the li¬ 
brary from Python, a de-facto standard interpreted language 
in science. Availability of the bindings enlarges the potential 
user base of libdoudph++. It also enlarges the range of the library 
applications by offering the possibility to couple libcloudph++ with 
numerous existing Python packages, e.g. with SciPy or CFFI 
as exemplified in this paper. 

The presented C-|—I-/Python/Fortran coupling method is, to the 
authors’ knowledge, a novel approach. While not being straight¬ 
forward, it has the advantage of offering productivity-oriented 
features of an interpreted language, even though the addressed 
problem concerns coupling of two compiled languages. 

A Obtsdning £md installing the bindings 

The Python bindings for libcloudph++ are shipped with the li¬ 
brary. The library uses CMake^ for build and test automation. 
Besides CMake, the library code depends on several components 
of the Boost C-F-1- library collection and on the Thrust® C-F-1- 
library. If available, the library will be compiled with support 
for parallelisation of the particle-based algorithm using OpenMP 
and CUBA. 

Listing 14 gives a set of commands that result in downloading 
the current development version of the library, compilation, execu¬ 
tion of test programs, and installation of the library and Python 
bindings on the system. For reference on how to use non-default 
compiler or how to use non-default paths, see documentation 
of CMake and the README file shipped with libdoudph++. 

^http: //cmake. org/ 

®https://thrust.github.io/ 
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